\chapter{错误代码与消息}
\label{app:errors}

本附录列出常见错误、触发原因及对应解决方案，方便快速排查。

\section{安装阶段错误}

\subsection{ERR-INSTALL-001：找不到 Python}

\textbf{报错示例}
\begin{lstlisting}
'python' is not recognized as an internal or external command
\end{lstlisting}
\textbf{原因}：未安装 Python 或 PATH 未配置

\textbf{解决}：参考第 \ref{ch:installation-linux} 或 \ref{ch:installation-windows} 章安装并加入 PATH。

\subsection{ERR-INSTALL-002：Python 版本过低}

\textbf{报错示例}
\begin{lstlisting}
ERROR: cpp-orchestrator requires Python 3.11 or higher
\end{lstlisting}
\textbf{原因}：当前 Python 版本低于 3.11

\textbf{解决}：升级至 3.11+，见第 \ref{sec:linux-python} 节。

\subsection{ERR-INSTALL-003：找不到 dotnet}

\textbf{报错示例}
\begin{lstlisting}
'dotnet' is not recognized as an internal or external command
\end{lstlisting}
\textbf{原因}：.NET SDK 未安装或 PATH 缺失

\textbf{解决}：安装 .NET SDK 8.0 并检查 PATH。

\subsection{ERR-INSTALL-004：pip 安装失败}

\textbf{报错示例}
\begin{lstlisting}
ERROR: Could not install packages due to an EnvironmentError:
[Errno 13] Permission denied
\end{lstlisting}
\textbf{原因}：权限不足

\textbf{解决}：
\begin{itemize}
    \item 使用 virtualenv（推荐）
    \item 或使用 \code{pip install --user}
    \item 避免使用 \code{sudo pip}
\end{itemize}

\section{转换阶段错误}

\subsection{ERR-CONV-001：ModuleNotFoundError}

\textbf{报错示例}
\begin{lstlisting}
ModuleNotFoundError: No module named 'orchestrator'
\end{lstlisting}
\textbf{原因}：环境中未安装 cpp-orchestrator 或 PYTHONPATH 未设置。

\textbf{解决}：激活虚拟环境或重新安装包。

\subsection{ERR-CONV-002：IR 解析失败}

\textbf{报错示例}
\begin{lstlisting}
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
\end{lstlisting}
\textbf{原因}：IR JSON 文件损坏。

\textbf{解决}：使用 `python -m json.tool` 验证 JSON，并重新生成 IR。

\subsection{ERR-CONV-003：类型映射失败}

\textbf{报错示例}
\begin{lstlisting}
TypeError: Cannot map C# type 'CustomType' to C++
\end{lstlisting}
\textbf{原因}：遇到未知 C\# 类型。

\textbf{解决}：添加自定义映射：

\begin{lstlisting}[language=Python]
mapper.add_custom_mapping(
    "CustomType",
    "my_namespace::CustomType",
    ["my_namespace/custom_type.hpp"],
)
\end{lstlisting}

\section{编译阶段错误}

\subsection{ERR-COMP-001：缺少头文件}

\textbf{报错示例}
\begin{lstlisting}
fatal error: namespace/file.hpp: No such file or directory
\end{lstlisting}
\textbf{原因}：编译时未包含生成目录。

\textbf{解决}：确保编译命令包含 `-I generated-cpp/include`，并检查文件是否存在。

\subsection{ERR-COMP-002：编译器不支持 C++20}

\textbf{报错示例}
\begin{lstlisting}
error: 'concepts' is not a keyword in C++14
\end{lstlisting}
\textbf{原因}：编译器默认标准过低。

\textbf{解决}：在命令中加入 `-std=c++20` 或升级编译器版本。

\subsection{ERR-COMP-003：链接失败}

\textbf{报错示例}
\begin{lstlisting}
undefined reference to `my_game::services::PlayerService::get_player()'
\end{lstlisting}
\textbf{原因}：未将对应的 .cpp 文件加入构建。

\textbf{解决}：在 CMake 或手动编译命令中补齐源文件列表。

\section{构建环境问题}

\begin{itemize}
    \item 使用 `cpp-orchestrator doctor` 自动检查环境
    \item 对于 Windows，建议使用 VS 2022 Developer Prompt 执行命令
    \item 对于 Linux，确保 `python`, `dotnet`, `g++` 均在 PATH 中
\end{itemize}

若遇到未覆盖的错误，可将日志提交至项目仓库或在内部知识库记录以便复用。
